request-promise
Advanced tools
The simplified HTTP request client 'request' with Promise support. Powered by Bluebird.
The request-promise npm package is a popular HTTP client for making HTTP requests from Node.js. It is built on top of the 'request' package, providing a simplified way to make HTTP calls and process responses using promises instead of callbacks.
Simple HTTP GET requests
This feature allows you to perform simple HTTP GET requests and process the response as a string.
const rp = require('request-promise');
rp('http://example.com')
.then(function (htmlString) {
// Process html...
})
.catch(function (err) {
// Handle error...
});HTTP requests with options
This feature allows you to perform HTTP requests with a full set of options, including query strings, headers, and automatic JSON parsing.
const rp = require('request-promise');
const options = {
uri: 'http://api.example.com',
qs: {
access_token: 'my-token' // -> uri + '?access_token=my-token'
},
headers: {
'User-Agent': 'Request-Promise'
},
json: true // Automatically parses the JSON string in the response
};
rp(options)
.then(function (repos) {
// Process repos...
})
.catch(function (err) {
// Handle error...
});POST requests with form data
This feature allows you to perform HTTP POST requests with form data.
const rp = require('request-promise');
const options = {
method: 'POST',
uri: 'http://api.example.com/form',
form: {
key: 'value',
another_key: 'another_value'
},
headers: {
/* 'content-type': 'application/x-www-form-urlencoded' */ // Is set automatically
}
};
rp(options)
.then(function (parsedBody) {
// POST succeeded...
})
.catch(function (err) {
// POST failed...
});Axios is a promise-based HTTP client for the browser and Node.js. It provides an easy-to-use API for making HTTP requests and can be used in both the front-end and back-end. It supports interceptors, request and response transformations, and automatic JSON data transformation, making it more feature-rich compared to request-promise.
Got is a human-friendly and powerful HTTP request library for Node.js. It is designed to be a simpler and more lightweight alternative to request-promise, with support for streams and promises. Got also provides a more modern API with built-in support for JSON and better error handling.
node-fetch is a light-weight module that brings the Fetch API to Node.js. It is a minimalistic and straightforward API that closely resembles the browser's fetch API, making it ideal for developers who prefer the fetch syntax and are looking for a simple way to make HTTP requests in Node.js.
Superagent is a small progressive client-side HTTP request library. It has a flexible and chainable API that allows for easy construction of complex queries. It is often compared to request-promise for its simplicity and ease of use but is more focused on being used in web browsers, although it works in Node.js as well.
As of Feb 11th 2020, request is fully deprecated. No new changes are expected to land. In fact, none have landed for some time. This package is also deprecated because it depends on request.
Fyi, here is the reasoning of request's deprecation and a list of alternative libraries.
The simplified HTTP request client 'request' with Promise support. Powered by Bluebird.
Request and Bluebird are pretty awesome, but I found myself using the same design pattern. Request-Promise adds a Bluebird-powered .then(...) method to Request call objects. By default, http response codes other than 2xx will cause the promise to be rejected. This can be overwritten by setting options.simple = false.
Also check out the new libraries that are very similar to request-promise v4:
request-promise-native v1 – Does not depend on Bluebird and uses native ES6 promises instead.request-promise-any v1 – Allows you to register any Promise library supported by any-promise.request became a peer dependency. Thus make sure that request is installed into your project as a direct dependency. (npm install --save request)request-promise-any.transform function to v3 and had to add if (!(/^2/.test('' + response.statusCode))) { return resolveWithFullResponse ? response : body; } you may now set the option transform2xxOnly = true instead.The handling of the transform function got overhauled. This has two effects:
StatusCodeError.response is the transformed instead of the original response now. This error is thrown for non-2xx responses when options.simple is true (default). Please update your transform functions to also cover the transformation of non-2xx responses. To get the old behavior you may add if (!(/^2/.test('' + response.statusCode))) { return resolveWithFullResponse ? response : body; } to the first line of your transform functions that are used for requests with options.simple === true. However, you may prefer updating your transform functions to being able to transform 2xx as well as non-2xx responses because this decouples their implementation from the use of the simple option when doing requests.TransformError. Its cause attribute contains the error thrown by the transform operation. Previously, the request was rejected directly with the error thrown by the transform operation. Wrapping it into a TransformError makes the error handling easier.Bluebird got updated from v2 to v3. This won't make a difference for most use cases. However, if you use advanced Promise chains starting with the Promise returned by Request-Promise, please check Bluebird's new features and changes.
This module is installed via npm:
npm install --save request
npm install --save request-promise
request is defined as a peer-dependency and thus has to be installed separately.
var rp = require('request-promise');
Since request-promise wraps around request everything that works with request also works with request-promise. Also check out the request docs for more examples.
rp('http://www.google.com')
.then(function (htmlString) {
// Process html...
})
.catch(function (err) {
// Crawling failed...
});
var cheerio = require('cheerio'); // Basically jQuery for node.js
var options = {
uri: 'http://www.google.com',
transform: function (body) {
return cheerio.load(body);
}
};
rp(options)
.then(function ($) {
// Process html like you would with jQuery...
})
.catch(function (err) {
// Crawling failed or Cheerio choked...
});
var options = {
uri: 'https://api.github.com/user/repos',
qs: {
access_token: 'xxxxx xxxxx' // -> uri + '?access_token=xxxxx%20xxxxx'
},
headers: {
'User-Agent': 'Request-Promise'
},
json: true // Automatically parses the JSON string in the response
};
rp(options)
.then(function (repos) {
console.log('User has %d repos', repos.length);
})
.catch(function (err) {
// API call failed...
});
Set option.body to your data and json: true to encode the body as JSON. See below for HTML forms.
var options = {
method: 'POST',
uri: 'http://api.posttestserver.com/post',
body: {
some: 'payload'
},
json: true // Automatically stringifies the body to JSON
};
rp(options)
.then(function (parsedBody) {
// POST succeeded...
})
.catch(function (err) {
// POST failed...
});
Pass your data to options.form to encode the body the same way as HTML forms do:
var options = {
method: 'POST',
uri: 'http://posttestserver.com/post.php',
form: {
// Like <input type="text" name="name">
name: 'Josh'
},
headers: {
/* 'content-type': 'application/x-www-form-urlencoded' */ // Is set automatically
}
};
rp(options)
.then(function (body) {
// POST succeeded...
})
.catch(function (err) {
// POST failed...
});
If you want to include a file upload then use options.formData:
var options = {
method: 'POST',
uri: 'http://posttestserver.com/post.php',
formData: {
// Like <input type="text" name="name">
name: 'Jenn',
// Like <input type="file" name="file">
file: {
value: fs.createReadStream('test/test.jpg'),
options: {
filename: 'test.jpg',
contentType: 'image/jpg'
}
}
},
headers: {
/* 'content-type': 'multipart/form-data' */ // Is set automatically
}
};
rp(options)
.then(function (body) {
// POST succeeded...
})
.catch(function (err) {
// POST failed...
});
var tough = require('tough-cookie');
// Easy creation of the cookie - see tough-cookie docs for details
let cookie = new tough.Cookie({
key: "some_key",
value: "some_value",
domain: 'api.mydomain.com',
httpOnly: true,
maxAge: 31536000
});
// Put cookie in an jar which can be used across multiple requests
var cookiejar = rp.jar();
cookiejar.setCookie(cookie, 'https://api.mydomain.com');
// ...all requests to https://api.mydomain.com will include the cookie
var options = {
uri: 'https://api.mydomain.com/...',
jar: cookiejar // Tells rp to include cookies in jar that match uri
};
rp(options)
.then(function (body) {
// Request succeeded...
})
.catch(function (err) {
// Request failed...
});
var options = {
method: 'DELETE',
uri: 'http://my-server/path/to/resource/1234',
resolveWithFullResponse: true // <--- <--- <--- <---
};
rp(options)
.then(function (response) {
console.log("DELETE succeeded with status %d", response.statusCode);
})
.catch(function (err) {
// Delete failed...
});
var options = {
uri: 'http://www.google.com/this-page-does-not-exist.html',
simple: false // <--- <--- <--- <---
};
rp(options)
.then(function (body) {
// Request succeeded but might as well be a 404
// Usually combined with resolveWithFullResponse = true to check response.statusCode
})
.catch(function (err) {
// Request failed due to technical reasons...
});
For more options checkout the Request docs.
Consider Request-Promise being:
require('request-promise') == require('request') so to say.pipe(...)) is DISCOURAGED because Request-Promise would grow the memory footprint for large requests unnecessarily high. Use the original Request library for that. You can use both libraries in the same project.rp(...).then(...) or e.g. rp.post(...).then(...) which turn rp(...) and rp.post(...) into promisesrp(...).catch(...) or e.g. rp.del(...).catch(...) which is the same method as provided by Bluebird promises
request library would pass to the callback are wrapped by request-promise and then passed to the catch handler. See code example below.rp(...).finally(...) or e.g. rp.put(...).finally(...) which is the same method as provided by Bluebird promisesrp(...).cancel() or e.g. rp.get(...).cancel() which cancels the requestrp(...).promise() or e.g. rp.head(...).promise() which returns the underlying promise so you can access the full Bluebird APIsimple = true which is a boolean to set whether status codes other than 2xx should also reject the promiseresolveWithFullResponse = false which is a boolean to set whether the promise should be resolved with the full response or just the response bodytransform which takes a function to transform the response into a custom value with which the promise is resolvedtransform2xxOnly = false which is a boolean to set whether the transform function is applied to all responses or only to those with a 2xx status codeThe objects returned by request calls like rp(...) or e.g. rp.post(...) are regular Promises/A+ compliant promises and can be assimilated by any compatible promise library.
The methods .then(...), .catch(...), and .finally(...) - which you can call on the request call objects - return a full-fledged Bluebird promise. That means you have the full Bluebird API available for further chaining. E.g.: rp(...).then(...).spread(...) If, however, you need a method other than .then(...), .catch(...), or .finally(...) to be FIRST in the chain, use .promise(): rp(...).promise().bind(...).then(...)
// As a Request user you would write:
var request = require('request');
request('http://google.com', function (err, response, body) {
if (err) {
handleError({ error: err, response: response, ... });
} else if (!(/^2/.test('' + response.statusCode))) { // Status Codes other than 2xx
handleError({ error: body, response: response, ... });
} else {
process(body);
}
});
// As a Request-Promise user you can now write the equivalent code:
var rp = require('request-promise');
rp('http://google.com')
.then(process, handleError);
// The same is available for all http method shortcuts:
request.post('http://example.com/api', function (err, response, body) { ... });
rp.post('http://example.com/api').then(...);
rp('http://google.com')
.catch(handleError);
// ... is syntactical sugar for:
rp('http://google.com')
.then(null, handleError);
// However, this:
rp('http://google.com')
.then(process)
.catch(handleError);
// ... is safer than:
rp('http://google.com')
.then(process, handleError);
For more info on .then(process).catch(handleError) versus .then(process, handleError), see Bluebird docs on promise anti-patterns.
rp('http://google.com')
.finally(function () {
// This is called after the request finishes either successful or not successful.
});
This method cancels the request using Bluebird's cancellation feature.
When .cancel() is called:
In order to not pollute the Request call objects with the methods of the underlying Bluebird promise, only .then(...), .catch(...), and .finally(...) were exposed to cover most use cases. The effect is that any methods of a Bluebird promise other than .then(...), .catch(...), or .finally(...) cannot be used as the FIRST method in the promise chain:
// This works:
rp('http://google.com').then(function () { ... });
rp('http://google.com').catch(function () { ... });
// This works as well since additional methods are only used AFTER the FIRST call in the chain:
rp('http://google.com').then(function () { ... }).spread(function () { ... });
rp('http://google.com').catch(function () { ... }).error(function () { ... });
// Using additional methods as the FIRST call in the chain does not work:
// rp('http://google.com').bind(this).then(function () { ... });
// Use .promise() in these cases:
rp('http://google.com').promise().bind(this).then(function () { ... });
resolveWithFullResponse option// Per default the body is passed to the fulfillment handler:
rp('http://google.com')
.then(function (body) {
// Process the html of the Google web page...
});
// The resolveWithFullResponse options allows to pass the full response:
rp({ uri: 'http://google.com', resolveWithFullResponse: true })
.then(function (response) {
// Access response.statusCode, response.body etc.
});
simple option// The rejection handler is called with a reason object...
rp('http://google.com')
.catch(function (reason) {
// Handle failed request...
});
// ... and would be equivalent to this Request-only implementation:
var options = { uri: 'http://google.com' };
request(options, function (err, response, body) {
var reason;
if (err) {
reason = {
cause: err,
error: err,
options: options,
response: response
};
} else if (!(/^2/.test('' + response.statusCode))) { // Status Codes other than 2xx
reason = {
statusCode: response.statusCode,
error: body,
options: options,
response: response
};
}
if (reason) {
// Handle failed request...
}
});
// If you pass the simple option as false...
rp({ uri: 'http://google.com', simple: false })
.catch(function (reason) {
// Handle failed request...
});
// ... the equivalent Request-only code would be:
request(options, function (err, response, body) {
if (err) {
var reason = {
cause: err,
error: err,
options: options,
response: response
};
// Handle failed request...
}
});
// E.g. a 404 would now fulfill the promise.
// Combine it with resolveWithFullResponse = true to check the status code in the fulfillment handler.
With version 0.4 the reason objects became Error objects with identical properties to ensure backwards compatibility. These new Error types allow targeted catch blocks:
var errors = require('request-promise/errors');
rp('http://google.com')
.catch(errors.StatusCodeError, function (reason) {
// The server responded with a status codes other than 2xx.
// Check reason.statusCode
})
.catch(errors.RequestError, function (reason) {
// The request failed due to technical reasons.
// reason.cause is the Error object Request would pass into a callback.
});
transform functionYou can pass a function to options.transform to generate a custom fulfillment value when the promise gets resolved.
// Just for fun you could reverse the response body:
var options = {
uri: 'http://google.com',
transform: function (body, response, resolveWithFullResponse) {
return body.split('').reverse().join('');
}
};
rp(options)
.then(function (reversedBody) {
// ;D
});
// However, you could also do something useful:
var $ = require('cheerio'); // Basically jQuery for node.js
function autoParse(body, response, resolveWithFullResponse) {
// FIXME: The content type string could contain additional values like the charset.
// Consider using the `content-type` library for a robust comparison.
if (response.headers['content-type'] === 'application/json') {
return JSON.parse(body);
} else if (response.headers['content-type'] === 'text/html') {
return $.load(body);
} else {
return body;
}
}
options.transform = autoParse;
rp(options)
.then(function (autoParsedBody) {
// :)
});
// You can go one step further and set the transform as the default:
var rpap = rp.defaults({ transform: autoParse });
rpap('http://google.com')
.then(function (autoParsedBody) {
// :)
});
rpap('http://echojs.com')
.then(function (autoParsedBody) {
// =)
});
The third resolveWithFullResponse parameter of the transform function is equivalent to the option passed with the request. This allows to distinguish whether just the transformed body or the whole response shall be returned by the transform function:
function reverseBody(body, response, resolveWithFullResponse) {
response.body = response.body.split('').reverse().join('');
return resolveWithFullResponse ? response : response.body;
}
As of Request-Promise v3 the transform function is ALWAYS executed for non-2xx responses. When options.simple is set to true (default) then non-2xx responses are rejected with a StatusCodeError. In this case the error contains the transformed response:
var options = {
uri: 'http://the-server.com/will-return/404',
simple: true,
transform: function (body, response, resolveWithFullResponse) { /* ... */ }
};
rp(options)
.catch(errors.StatusCodeError, function (reason) {
// reason.response is the transformed response
});
You may set options.transform2xxOnly = true to only execute the transform function for responses with a 2xx status code. For other status codes – independent of any other settings, e.g. options.simple – the transform function is not executed.
If the transform operation fails (throws an error) the request will be rejected with a TransformError:
var errors = require('request-promise/errors');
var options = {
uri: 'http://google.com',
transform: function (body, response, resolveWithFullResponse) {
throw new Error('Transform failed!');
}
};
rp(options)
.catch(errors.TransformError, function (reason) {
console.log(reason.cause.message); // => Transform failed!
// reason.response is the original response for which the transform operation failed
});
Continuation Local Storage is no longer supported. However, you can get back the support by using request-promise-any.
The ways to debug the operation of Request-Promise are the same as described for Request. These are:
NODE_DEBUG=request node script.js (lib,request,otherlib works too).require('request-promise').debug = true at any time (this does the same thing as #1).require('request-debug')(rp);.Usually you want to mock the whole request function which is returned by require('request-promise'). This is not possible by using a mocking library like sinon.js alone. What you need is a library that ties into the module loader and makes sure that your mock is returned whenever the tested code is calling require('request-promise'). Mockery is one of such libraries.
@florianschmidt1994 kindly shared his solution:
before(function (done) {
var filename = "fileForResponse";
mockery.enable({
warnOnReplace: false,
warnOnUnregistered: false,
useCleanCache: true
});
mockery.registerMock('request-promise', function () {
var response = fs.readFileSync(__dirname + '/data/' + filename, 'utf8');
return Bluebird.resolve(response.trim());
});
done();
});
after(function (done) {
mockery.disable();
mockery.deregisterAll();
done();
});
describe('custom test case', function () {
// Test some function/module/... which uses request-promise
// and it will always receive the predefined "fileForResponse" as data, e.g.:
var rp = require('request-promise');
rp(...).then(function(data) {
// ➞ data is what is in fileForResponse
});
});
Based on that you may now build a more sophisticated mock. Sinon.js may be of help as well.
To set up your development environment:
cd to the main folder,npm install,npm install gulp -g if you haven't installed gulp globally yet, andgulp dev. (Or run node ./node_modules/.bin/gulp dev if you don't want to install gulp globally.)gulp dev watches all source files and if you save some changes it will lint the code and execute all tests. The test coverage report can be viewed from ./coverage/lcov-report/index.html.
If you want to debug a test you should use gulp test-without-coverage to run all tests without obscuring the code by the test coverage instrumentation.
request-promise-core which bumps lodash to ^4.17.19 following this advisory.request-promise-core which bumps lodash to ^4.17.15. See vulnerabilty reports.
(Thanks to @rishabh-chowdhary for reporting this in pull request #326.)tough-cookie version, now ^2.3.3
(Thanks to @evocateur for pointing this out.)request-promise@4.2.3 please make sure after the upgrade that request and request-promise use the same physical copy of tough-cookie.tough-cookie@~2.3.3 to avoid installing tough-cookie@3 which introduces breaking changes
(Thanks to @aomdoa for pull request #299)lodash to ^4.17.11, see vulnerabilty reportstough-cookie to a version without regex DoS vulnerability
(Thanks to @rouanw for pull request #226)tough-cookie for cookie creation
(Thanks to @ScottyMJacobson for reporting issue #183)bluebird to v3.5
(Thanks to @acinader for pull request #181)@request/promise-core version for safer versioningrequest is declared as a peer dependency which has to be installed separately by the user nowrequest-promise-any can be used for that nowtransform2xxOnly option to ease the breaking change regarding the new transform handling in v3.0.0
(Thanks to @stevage for pointing out the effect of the breaking change in issue #131)request-promise-native and request-promise-any
(Thanks to @benjamingr, @eilgin, @gillesdemey, @hildjj, @iggycoloma, @jonathanong, @knpwrs, @MarkHerhold, @massimocode, @mikeal, @niftylettuce, @raitucarp, @sherdeadlock, @tonylukasavage, and @vgoloviznin for the valuable discussions!)transform function
(Thanks to @Limess for explaining the need in issue #86)bluebird to v3
(Thanks to @BrandonSmith for pull request #103)StatusCodeError.messagelodash to v4.6.catch(...) best practice
(Thanks to @RebootJeff for pull request #98)lodash to v4
(Thanks to @ratson for pull request #94)cls-bluebird dependency which has to be installed by the user now
(Thanks to @hildjj for his pull request #75)npm shrinkwrap now works for npm@3 users who don't use continuation-local-storage
(Thanks to @toboid and @rstacruz for reporting the issue in issue #70 and issue #82)continuation-local-storage from peer dependencies as it was unnecessary
(Thanks to @mrhyde for working on a better solution discussed in issue #70)continuation-local-storage as a peer dependencyresolveWithFullResponse = true is used)
(Thanks to @zcei for proposing the change in issue #58)transform function by a third resolveWithFullResponse parametertypeof reason === 'object' still holds true and the error objects have the same properties as the previous reason objects. If the reject handler only accesses the properties on the reason object - which is usually the case - no migration is required..finally(...) to allow using it as the first method in the promise chain
(Thanks to @hjpbarcelos for his pull request #28).promise() method for advanced Bluebird API usage
(Thanks to @devo-tox for his feedback in issue #27)In case you never heard about the ISC license it is functionally equivalent to the MIT license.
See the LICENSE file for details.
FAQs
The simplified HTTP request client 'request' with Promise support. Powered by Bluebird.
The npm package request-promise receives a total of 1,117,220 weekly downloads. As such, request-promise popularity was classified as popular.
We found that request-promise demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.